Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@header/src/main/java/org/zstack/header/storage/primary/APIChangeVolumeProtocolMsg.java`:
- Around line 10-15: The REST annotation on APIChangeVolumeProtocolMsg currently
uses HttpMethod.POST but this operation updates an existing volume resource;
change the annotation's method from HttpMethod.POST to HttpMethod.PUT in the
`@RestRequest` on class APIChangeVolumeProtocolMsg to reflect an update semantics
(this will also cause the SDK's ChangeVolumeProtocolAction to be synced when you
regenerate the SDK).

In
`@storage/src/main/java/org/zstack/storage/addon/primary/ExternalPrimaryStorage.java`:
- Around line 2391-2395: The SQL update on VolumeVO
(SQL.New(VolumeVO.class).eq(VolumeVO_.uuid,
msg.getVolumeUuid()).set(VolumeVO_.protocol, msg.getProtocol()).update())
currently always calls completion.success() even when no rows are affected;
change this to capture the update() return (affected rows) and if it's >0 call
completion.success(), otherwise call completion.fail(...) with a clear error
(e.g., "no volume updated for uuid ...") so callers don't treat a no-op as
success; keep existing use of msg.getVolumeUuid(), msg.getProtocol(), and
completion.success()/completion.fail() in the revised flow.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@conf/db/upgrade/V5.5.28__schema.sql`:
- Around line 7-8: Replace the zero timestamp default on the createDate column
with a non-zero sentinel value so the migration works in strict SQL mode and
coexists with the existing lastOpDate TIMESTAMP that has ON UPDATE
CURRENT_TIMESTAMP; specifically, change the createDate definition (`createDate`
timestamp NOT NULL DEFAULT '0000-00-00 00:00:00') to use a non-zero sentinel
(e.g., '1970-01-01 00:00:01') rather than DEFAULT CURRENT_TIMESTAMP, leaving
`lastOpDate` (`lastOpDate` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00' ON
UPDATE CURRENT_TIMESTAMP) behavior intact.

In `@docs/zbs-vhost/40-frontend-protocol-api.md`:
- Around line 18-20: 在 docs/zbs-vhost/40-frontend-protocol-api.md 中的 5 个 fenced
code block（例如包含文本 "NVMEoF | iSCSI | Vhost | CBD | NBD | RBD"、示例请求行 "GET
/zstack/v1/external-primary-storage/host-protocol-refs?q=primaryStorageUuid=xxx"
/ "GET
/zstack/v1/external-primary-storage/{primaryStorageUuid}/host-protocol-refs"，以及请求体起始行
"POST /zstack/v1/primary-storage/protocol" 和 "{ \"params\": {"）都缺少 language
标识，导致 MD040 警告；为每个代码块在起始 ``` 后加上合适的语言标识（至少使用 text、http 或 json，分别对应纯文本、HTTP 请求示例和
JSON 请求体），确保每个块的语法高亮与示例内容匹配（例如将表格行标为 text，将 GET/POST 请求示例标为 http，将 JSON 体标为
json）。
- Around line 118-123: The documentation contains contradictory statements about
DiskOfferingVO.protocol (mentioned in §5 and §9)—decide a single authoritative
status (either "reserved/planned" or "deprecated/cancelled"), update the
protocol source priority list so it reflects that decision (adjust the numbered
list where DiskOfferingVO.protocol appears), and make the same change to the
other occurrence referenced (lines ~174-175) so both sections consistently state
the final status and behavior for DiskOfferingVO.protocol.

In
`@plugin/externalStorage/src/main/java/org/zstack/externalStorage/primary/kvm/ExternalPrimaryStorageKvmFactory.java`:
- Around line 223-255: The code doesn't handle a null/empty
returnValue.getHealthy(), which makes allMatch(...) return true and may
incorrectly set the host-level status to Connected or cause an NPE; update the
logic in the WhileDoneCompletion after the per-protocol loop to first check if
returnValue.getHealthy() is null or empty, and if so call
updateHostStatus(host.getUuid(), extPs.getUuid(), null,
PrimaryStorageHostStatus.Disconnected, operr(..., "no protocols reported for
host..."), compl) (include a clear error via operr like other branches);
otherwise keep the existing defaultReported check and the folded allMatch(...)
logic that maps StorageHealthy to PrimaryStorageHostStatus and calls
updateHostStatus.

In
`@sdk/src/main/java/org/zstack/sdk/QueryExternalPrimaryStorageHostProtocolRefResult.java`:
- Around line 6-11: 在 QueryExternalPrimaryStorageHostProtocolRefResult 中，字段
inventories 及其访问器 setInventories/getInventories 使用的是原始
java.util.List，导致反序列化丢失元素类型并变成 Map/LinkedTreeMap；将该字段和方法签名改为使用泛型
List<ExternalPrimaryStorageHostProtocolRefInventory>（或全限定名）并添加必要的 import，确保
getter/setter 的参数和返回类型一致，以便 SDK 反序列化出正确的
ExternalPrimaryStorageHostProtocolRefInventory 对象。

In
`@storage/src/main/java/org/zstack/storage/addon/primary/ExternalPrimaryStorage.java`:
- Around line 343-355: The updateHostProtocolStatus method currently does a
read-then-write using Q.New(...).find() followed by dbf.persist/update which
races under concurrent reports; change it to an atomic upsert on the natural key
(primaryStorageUuid, hostUuid, protocol) in
ExternalPrimaryStorageHostProtocolRefVO: attempt an UPDATE by that key first
(set status = newStatus), check affected rows and if zero then INSERT the new
row while catching unique-constraint violations to retry the UPDATE path; ensure
the database defines a unique constraint on (primaryStorageUuid, hostUuid,
protocol) so concurrent callers converge to a single row.
- Around line 2435-2440: The failure handler in onProtocolAdded() must not
proceed to register the protocol; remove the call to
ExternalPrimaryStorage.super.doAddProtocol(msg, completion) from the
fail(ErrorCode) path and instead call completion.fail(errorCode) (or otherwise
propagate the error) so the protocol is not exposed when host preparation
failed. Ensure doAddProtocol(msg, completion) is only invoked from the
successful onProtocolAdded() path (or after verifying at least one host is
Connected and prepared), and keep the existing logger.warn with the error
details.

In `@storage/src/main/java/org/zstack/storage/volume/VolumeApiInterceptor.java`:
- Around line 491-509: The validateVolumeProtocol method currently treats only
null as "unspecified" but should also treat empty/blank strings as unspecified;
update the early-exit check in validateVolumeProtocol so that if protocol is
null or blank (e.g., protocol.trim().isEmpty() or using a StringUtils.isBlank
equivalent) it returns immediately, leaving the enum check and the
PrimaryStorageOutputProtocolRefVO existence check
(Q.New(...).eq(...).isExists()) to run only for truly explicitly-specified
protocol values; keep all existing exception types
(ApiMessageInterceptionException / argerr) unchanged for invalid/unknown
protocols.

In
`@test/src/test/groovy/org/zstack/test/integration/storage/primary/addon/zbs/ZbsVhostVolumeCase.groovy`:
- Around line 468-472: The test changes the global config "host.ping.interval"
to 1 via updateGlobalConfig but never restores it; capture the original value
before calling updateGlobalConfig (in the test method inside class
ZbsVhostVolumeCase or the surrounding setup block), and ensure you restore it in
the finally block (or add a finally if none) by calling updateGlobalConfig with
the saved original value so the global state is not leaked to subsequent tests.
- Around line 434-457: The test can pass spuriously because an existing
ExternalPrimaryStorageHostProtocolRefVO(protocol=Vhost) row may remain from
attachPrimaryStorageToCluster(); before calling addStorageProtocol (and after
deleting PrimaryStorageOutputProtocolRefVO), also delete any
ExternalPrimaryStorageHostProtocolRefVO rows matching
primaryStorageUuid=ps.uuid, hostUuid=host.uuid,
protocol=VolumeProtocol.Vhost.toString() so the subsequent isExists() truly
verifies a new/write update, or alternatively change the assertion to verify
that the existing ExternalPrimaryStorageHostProtocolRefVO's lastOpDate was
advanced by addStorageProtocol (compare previous lastOpDate to a later value)
and still assert ensureCalled reached VHOST_TARGET_ENSURE_PATH; locate these
changes around attachPrimaryStorageToCluster(), the addStorageProtocol block,
ensureCalled and the isExists() retry.

---

Nitpick comments:
In
`@test/src/test/groovy/org/zstack/test/integration/storage/primary/addon/zbs/ZbsVhostVolumeCase.groovy`:
- Around line 262-270: testCreateDataVolumeWithExplicitProtocol currently
depends on testChangeVolumeProtocol to add the CBD protocol to the primary
storage; make the test self-contained by adding the call that enables CBD for
the target primary storage inside this test's setup. Locate
testCreateDataVolumeWithExplicitProtocol and, before invoking createDataVolume,
call the same helper used to register protocols (e.g.
addStorageProtocol(VolumeProtocol.CBD) or the project-specific helper that
modifies the PS protocol list) against ps.uuid so CBD is present for this test
only; ensure this setup runs even if testChangeVolumeProtocol does not run.